Learn about ImageKit's APIs, authentication, rate limits, error codes, and more.
ImageKit.io offers REST APIs to programmatically integrate ImageKit.io into your application, especially the integrated Digital Asset Management or the media storage called the Media Library. Currently, APIs are available for the following operations.
File Upload APIs - Upload files to the ImageKit Media Library from the server or client side.Digital Asset Management APIs - Build a Headless DAM solution by natively integrating the ImageKit Media Library with search, list, copy, move, and other operations exposed via APIs.File Metadata APIs - Get a file's metadata by its file ID or URL.Custom Metadata Fields APIs - Create, read, and update custom metadata fields in your ImageKit Media Library via APIs. These fields can then be updated for your files via the Update File or Upload File API.Cache Management APIs - Initiate cache purge requests and check their status via APIs.Account Management APIs - Get the usage for your account between two dates.All these methods are available in our backend SDKs. We recommend using the SDKs for a more straightforward integration with your code. Upload APIs can also be used from the client side.
Request and response structureExcept for upload API, all our APIs accept JSON-encoded request bodies and return JSON-encoded responses.
Run in PostmanWe鈥檝e created a Postman collection to simplify testing and working with our API.
OpenAPI specificationHere is the OpenAPI specification for v1 version of ImageKit's API.
Error codesImageKit.io API uses standard HTTP error codes.
Error code Description 2xx OKEverything worked as expected.400 Bad requestThe request was unacceptable, often due to missing or invalid parameter(s). In this case, a JSON-encoded error response is returned with the message property. message contains the details about the error and possible solution.401 UnauthorizedNo valid API key was provided.403 ForbiddenCan be for the following reasons, which will be indicated in the message field in the response:ImageKit could not authenticate your account with the keys provided.An expired key (public or private) was used with the request.The account is disabled.If you are using the upload API, the total storage limit (or upload limit) is exceeded.429 Too Many RequestsToo many requests hit the API too quickly. We recommend you throttle the request rate as per the value of X-RateLimit-Limit and X-RateLimit-Reset response headers and stay within rate limits.500, 502, 503, 504 Server errorSomething went wrong with ImageKit.io API. Please create a support ticket by emailing us at support@imagekit.io.Request ID (x-ik-requestId)All API responses contain a x-ik-requestId header. This header's value is a unique identifier associated with the API request. If you encounter any issues with any API, provide this header value in your support ticket to help us troubleshoot the issue quickly. This is also exposed in all SDKs as part of the response object. Please refer to the respective SDK documentation for more details.
AuthenticationYour API requests are authenticated using the account's private API key. If you do not include your key when making an API request or use an incorrect one, we return an error. You can view your API keys in the ImageKit.io dashboard under the developer's tab.
Authentication to the API is performed via HTTP Basic Auth. Provide your private API key as the basic auth username value. You do not need to provide a password.
Only HTTPS supported All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.
ExampleYou can provide the private API key in a curl request as:
Copycurl https://api.imagekit.io/v1/files \ -u your_private_api_key:# The colon prevents curl from asking for a password.You can also use the "Authorization" header and provide base64 encoded value of the string your_private_api_key:
Notice the colon (:) after the private key. It is required. Otherwise, authentication will fail. The format is username:password. username is your private key and password is an empty string.
If you encode your_private_api_key: using base64, you will get eW91cl9wcml2YXRlX2FwaV9rZXk6
Copycurl https://api.imagekit.io/v1/files \ -H 'Authorization: Basic eW91cl9wcml2YXRlX2FwaV9rZXk6'Rate limitsExcept for the upload API, all our APIs are rate-limited to protect our infrastructure from excessive request rates and to keep ImageKit.io fast and stable for everyone.
Rate limiting is done across the account. When you exceed the rate limits for an endpoint, you will receive a 429 (Too many requests) response code.
If you receive a response status code of 429 (Too Many Requests), please sleep/pause for the number of milliseconds specified by the value of X-RateLimit-Reset response header before making additional requests to that endpoint.
Interval windowRate limits are specified for a specific interval. So, if an endpoint allows 100 requests per second (1000 milliseconds), and you exceed this rate, your application will receive a 429 response code. As explained below, every endpoint can have different limits, which are exposed via rate-limiting headers.
A single endpoint can have multiple limits, for example, a 100 request per second limit along with 1000 limits for a 15-minute duration.
Response headers to understand rate limitsYou will also receive the following response headers in response to every API request that hits the rate limit. Use these headers to stay within rate limits or pause/sleep your workflow in case you exceed them.
Response header Description X-RateLimit-LimitThe maximum number of requests that can be made to this endpoint in the interval specified by X-RateLimit-Interval response header.X-RateLimit-ResetThe amount of time in milliseconds before you can make another request to this endpoint. Pause/sleep your workflow for this duration.X-RateLimit-IntervalThe duration of the interval in milliseconds for which this rate limit was exceeded.Request higher rate limitsIf your workflow demands a higher rate limit, please contact us at support@imagekit.io.